COMMENT ⊗   VALID 00006 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002	PASCAL is  a programming language based on  ALGOL-60, developed by N.
C00003 00003	<DOCUMENTATION>
C00004 00004	<HOW TO USE IT>
C00006 00005	<SWITCHES>
C00013 00006	<DEBUGGING>
C00019 ENDMK
C⊗;
PASCAL is  a programming language based on  ALGOL-60, developed by N.
Wirth and  featuring powerful data-structure manipulation facilities,
plus a very clean and neat syntax.

The PASCAL compiler at LOTS is the DECUS version, developed at the 
University of Hamburg. It is an improved, fast and reliable version.

Comments, sugestions, gripes, etc.,about PASCAL to J.JHENN
	about this help file, to A.ARMANDO.

Subtopics:  DOCUMENTATION
	    HOW TO USE IT
	    SWITCHES
	    DEBUGGING

<DOCUMENTATION>

The documentation available is:

The Book: PASCAL, User Manual and Report, by Kathleen Jensen and 
		Niklaus Wirth, available at the Bookstore. Describes
		the standard language.

The Files: DOC:PASCAL.MAN Describes the diferences between DECUS PASCAL
			and the standard language. It is a long file.
			Hardcopies are available in the lobby at LOTS
			and in the CS library.
	   DOC:PASCAL.NOTES  Contains user comments on the LOTS version.
			Useful information, not available anywhere else,
			is found there.

<HOW TO USE IT>

  To use it, make a  source file of PASCAL (with the extension ".pas"),
 named  for example "squigl.pas" and proceed as follows:

[lower case indicates user input]

	@execute squigl
	
	PASCAL: SQUIGL [GRAPH     ]
	
	   0 ERROR(S) DETECTED
	
	HIGHSEG:   0K +  119 WORD(S)
	LOWSEG :   0K +  100 WORD(S)
	
	RUNTIME:   0: 0.401
	LOADING

	GRAPH 1+3K CORE
	EXECUTION
	OUTPUT    = blatzo
	
	EXIT

Now you  can look at your output file  ("blatzo")!  Note that when it
began  execution the  program prompted  for the  name to  use for the
output  file. Unfortunately, this  file must be on  disk, i.e. things
like "tty:"  for the  terminal are  not allowed.   However,  standard
files for  tty input and output (both named TTY) are built into the 
Pascal implementation. Note also that file names are restricted to six
characters, and extensions to three. The extensions for INPUT and OUTPUT
should be INP and OUT, respectively.

If   you  discover  anything   about  the  compiler,   append  it  to
DOC:PASCAL.NOTES .

<SWITCHES>

You can declare several options by using the compiler switches. There are
three ways to use them:

  1.-  In the execute command. You type them after the file name.
Some useful switches are:
	/LIST		Produces a listing of your program in the Line Printer.
	/CREF		Produces a file with extension .NEW which contains
			your program, prettyprinted, and another file with
			extension .LST, which contains a structure analisis
			and a cross reference. Cancels /LIST if included.
	/NOOBJECT	Cancels the production of the .REL file.

Note that, when using /CREF, after the compilation is done, a star (*)
will be printed. At that moment, type the name of your program file,
without extension. Then the cross reference will be produced.

  2.-  Calling the compiler directly. e.g., to execute the same file 
asking for runtime code for array boundary and arithmetic checks,
listing it on another file and enabling debuging, you do it this way:

[lower case indicates user input]
	@pascal
	  OBJECT = first.rel
	  LIST = first.lst
	  SOURCE = first.pas/check/debug/list

Note that you can put the switches following any of the file names you give.

  3.-  with so-called compiler options in the body of your program. e.g.
to obtain the same effect shown above, you include at the beginning of 
your program a comment line with a $ as the first character, like this:

	(*$T+,E+    the rest is comment*)

(Note that there is no compiler option to list the source file.)
Now, you can @execute or call @pascal, whichever you want.

Following is a table showing all the switches available for options 2
(at translation time) and 3 (in source program). Note that some of them are
available at translation time only. The negative option, when existent,
is included after the positive.

NOTES:	(*)   Specify it for the first time BEFORE the program heading.
	(**)  Cannot be reset anymore inside the program.

 ---------------------------------------------------------------------
:Function			:Specification		:Default
:				:in source program	:
:				:	:at translation	:
:				:	:   time	:
----------Compiler-options-------------------------------------------

List object code as MACRO-10.	L+	  CODE		off
				L-	NOCODE		

Perform runtime tests.		T+	  CHECK		on
 1) array indices		T-	NOCHECK
 2) assignments to subranges
 3) zero-divide
 4) arithmetic overflow
 5) variables in SET-constants
 6) input to file variables or
    variables of subrange types

Enable debugging including	D+	  DEBUG		off
Post-Mortem dump. (*)		D-	NODEBUG
P is equivalent to D for        P+
compatibility with PASCAL 6000 	P-

All level-1 procedures or	E+	  EXTERN	off
functions of a program may be	E-	NOEXTERN
activated by other programs.(**)

Only the first 72 characters	U+	  CARD		off
of a source program line are	U-	NOCARD
accepted for compilation
(card format). (**)

Maximum number of instructions	Sn 	  CODESIZE:n	n=1000
that may be generated for the
statement part of a "main program"
procedure or function.(**)

Size of low-segment in K	Rn	  RUNCORE:n	n=static core reqmt.
words. (**)						for total low-segment

Enable FORTRAN-I/O in external	I+	  FORTIO   	off
FORTRAN subroutines. (**)	I-	NOFORTIO

Highest register used to 	Xn	  REGISTER:n	n=6
pass parameters, with n in
[2..12]. External procedures
must be compiled with the
same value that is assumed
in the main program. (**)

Generate listing. 			  LIST		on
					NOLIST

----------"COMPIL-class" Command-options-----------------------------

Enforce compilation.			  COMPILE	depends on creation
					NOCOMPILE	date or .REL and
							.PAS file

Generate cross-reference list.	  	  CREF		off
(see note in EXEC switches above)	NOCREF		

----------Loader Command-options-------------------------------------

Provide information about all		  MAP		off
programs loaded.			NOMAP

Put a program library on top 		  SEARCH <lib>	PASLIB and
of the library search chain.				FORLIB
(<lib> ::= <file description>)

<DEBUGGING>
	
	   The	PASCAL DEBUG-system is only accessible to programs which have
	 been compiled with the /DEBUG option. It helps to have a listing of 
	 the program at hand, since the system is linenumber oriented.

		     When the program is executed, the first thing it types
	(after an asterisk if TTY is used, to which you answer with a <CR>),
	is the next message, at an initial, system-set breakpoint:
	
		$DEBUG: <program name>
		$
	
	At this point, you can type one or more of the next commands:
	
STOP <line>		Sets a new breakpoint at <line>,
	 where <line> is of the form linenumber/pagenumber or just linenumber
	 which is equivalent to linenumber/1 -	e.g.: 120/3 - . A  maximum of
	 20 breakpoints may be set simultaneously.
	
STOP NOT <line>		clears a previously set breakpoint.
	
LIST			Lists the currently set breakpoints.
	
<variable> =		displays the current value of <variable>.
	 <variable> may be any variable as allowed by  the PASCAL definition.
	 In particular it may be just a component of a structured variable or
	 the whole structure itself.  The  buffervariable  FILNAM↑  connected
	 with  the  file  identifier  FILNAM  as  well as the file identifier
	 itself can be accessed. If the  file  identifier  is  examined,  the
	 contents of the "file control block" are given.
	
STACKDUMP		generates a .TXT file with a source-level dump of the
	 current stack. If the DEBUG-option has been switched off locally  in
	 the program text, the error message "THERE IS NO  INFORMATION	ABOUT
	 THIS PART OF THE PROGRAM" may be output.
	
HEAPDUMP		generates a .TXT file with a source-level dump of the
	 current heap. If the DEBUG-option has been switched off locally, the
	 error messages "CAN'T CONTINUE THE HEAP DUMP" or "TYPE OF REFERENCED
	 VARIABLE  NOT	KNOWN"	might appear. After STACKDUMP or HEAPDUMP the
	 next message is typed:
	
		$LOOK FOR DUMP ON FILE XXXXXX.PMD
	
	 where XXXXXX is some fantasy name.
	
<variable> := <variable or constant>		Assigns a new value to a
	 variable. The assignment follows the usual type rules of PASCAL.
	
TRACE		Displays the currently active call sequence.
	 The names of the procedures and functions and their active line 
	 numbers are  printed  in  reverse  order   of	their activation.
	
END		Continues program execution.
	 The  program  will  run until another breakpoint is encountered. The
	 breakpoint is announced by
	
		$STOP AT <line>
		$

NOW: BESIDES BREAKPOINTS, DOES IT STOP ANYWHERE ELSE?
	
	   If a program -compiled with the DEBUG-option-  is  interrupted  by
	 any run-time error or by
	
		↑C↑C
	
	 the DEBUG-system is usually automatically entered or -if not- it  is
	 possible  to  (re-)  enter the DEBUG-system with the monitor command
	 DDT. The DEBUG-system outputs the message
	
		$STOP BY RUNTIME ERROR IN <program name>
		$STOP IN <line>:<line>
		$
	
	or	$STOP BY DDT COMMAND IN <program name>
		$STOP IN <line>:<line>
		$
	
	   If the program is running in "batch	mode",	the  DEBUG-system  is
	 automatically entered and a Post-Mortem dump is generated.
 
TO DEBUG EXTERNAL PROGRAMS:
	
	   If the main program and/or several  external  programs  have  been
	 compiled  with  the  DEBUG-option,  it  is the loading sequence -the
	 sequence in which the programs are specified  in  the	LOAD-command-
	 that indicates which program is to  be  debugged.   ONLY  the	first
	 program in the loading sequence may be debugged provided it has been
	 compiled with the DEBUG-option.
	
	Example:
	
		.LOAD MAIN, P1, P2		MAIN can be debugged
		.LOAD P1, MAIN, P2		now P1 can be debugged